Using Custom Behaviors

Overview

The SDKFakeActionRequestCallback interface is designed to simulate various actions that a real card reader might request during a transaction flow. These actions are represented through the sealed class SDKFakeReaderActionRequest, which defines different scenarios that could occur in a real device.

This interface allows developers to implement custom behaviors by responding to specific action requests from the simulated reader. Depending on the indicated action, a corresponding operation can be executed, and the result will vary based on the nature of that action.

---

Start Scanning (OnScannerStart)

When simulating a scanning process, the callback will be invoked, requesting the implementer to provide one of the following possible actions:

CompleteScanner

Indicates a successful scanning process, specifying how many devices were found.

SDKFakeInstallerProvider.getInstaller(
    object : SDKFakeActionRequestCallback {
        override fun onActionRequired(readerActionRequest: SDKFakeReaderActionRequest) {
            when (readerActionRequest) {
                is SDKFakeReaderActionRequest.OnScannerStart -> 
                    readerActionRequest.provideAction(
                        SDKFakeReaderActionRequest.OnScannerStart.ScannerStartAction.CompleteScanner(
                            deviceAmount = <DEVICE_AMOUNT>
                        )
                )
                else -> { /* Other actions */ }
            }
        }
    }
)

• DEVICE_AMOUNT parameter represents the number of devices found during a simulated scanning process. This value indicates the number of devices to be displayed as a result of the scan.

FinishWithError

Indicates the scanning process has failed and includes details about the error. The callback will specify:

• Type: Specifies the reason for the error using one of the defined SDKScannerResultListener.ErrorType options:
  • PermissionNotGiven: The scanner requires permissions that have not been granted. A list of required permissions (listPermissionNeeded) is provided.
  • BluetoothNotAvailable: The scanner cannot access the Bluetooth controller of the device.
  • BluetoothIsOff: Bluetooth is turned off and must be enabled for scanning.
  • LocationIsOff: Location services are turned off and must be enabled for scanning.
• Message: An optional parameter (String?) that can include a description of the error or additional details. If no message is provided, this can be null.

These errors will be reflected in the SDKScannerResultListener interface's onError method when the scan method of the SDKDeviceScanService class is invoked.

SDKFakeInstallerProvider.getInstaller(
    object : SDKFakeActionRequestCallback {
        override fun onActionRequired(readerActionRequest: SDKFakeReaderActionRequest) {
            when (readerActionRequest) {
                is SDKFakeReaderActionRequest.OnScannerStart ->
                    readerActionRequest.provideAction(
                        SDKFakeReaderActionRequest.OnScannerStart.ScannerStartAction.FinishWithError(
                            type = SDKScannerResultListener.ErrorType.PermissionNotGiven(
                                listPermissionNeeded = listOf("Location")
                            ),
                            message = "PermissionNotGiven"
                        )
                )
                else -> { /* Other actions */ }
            }
        }
    }
)

Connection Attempt (OnConnectionAttemptRequested)

Represents the reader's attempt to establish a connection. You can specify whether the connection was successful using the Boolean parameter connectionIsSuccessful.

SDKFakeInstallerProvider.getInstaller(
    object : SDKFakeActionRequestCallback {
        override fun onActionRequired(readerActionRequest: SDKFakeReaderActionRequest) {
            when (readerActionRequest) {
                is SDKFakeReaderActionRequest.OnConnectionAttemptRequested -> 
                    readerActionRequest.provideAction(
                        connectionIsSuccessful = <CONNECTION_IS_SUCCESSFULL>
                    )
                else -> { /* Other actions */ }
            }
        }
    }
)

• CONNECTION_IS_SUCCESSFULL:
  • If true is provided: The reader will simulate a successful connection, continuing with the simulated transaction flow.
  • If false is provided: The connection to the reader will fail, resulting in a recoverable error SDKTransactionError.ConnectionFailed.

Reader Information (OnReaderInfoRequired)

Requests details about the simulated device. You can provide this information using an SDKDeviceInfo object.

The information provided here will be reflected in the various states of the SDKReaderState class, representing the current status of the simulated reader. This state is returned through the onReaderStateChanged function of the SDKTransactionListener interface,

SDKFakeInstallerProvider.getInstaller(
    object : SDKFakeActionRequestCallback {
        override fun onActionRequired(readerActionRequest: SDKFakeReaderActionRequest) {
            when (readerActionRequest) {
                is SDKFakeReaderActionRequest.OnReaderInfoRequired ->
                    readerActionRequest.provideReaderInfo(
                      readerInfo = SDKDeviceInfo( // DEVICE_INFO
                            id = "19011201801310501018",
                            firmware = "3.87.3.15",
                            serial = "FAKE1310501018",
                            hardwareVersion = "A19I",
                            model = SDKDeviceModel.Fake,
                            hasPrinter = false
                        )
                    )

                else -> { /* Other actions */ }
            }
        }
    }
)

• DEVICE_INFO is object, which includes the device's essential attributes such as ID, firmware version, serial number, hardware version, model, and whether it has a printer.

Card Reading Behavior (OnCardBehaviourRequired)

Configures how the simulated reader handles card reading during a transaction. This action allows you to simulate different behaviors, such as approved or declined card transactions, and specify the details of the card being used.

ApproveCardRead

Simulates a card read that is approved and requires online authorization. The card details are provided using the SDKFakeCard object.

SDKFakeInstallerProvider.getInstaller(
    object : SDKFakeActionRequestCallback {
        override fun onActionRequired(readerActionRequest: SDKFakeReaderActionRequest) {
            when (readerActionRequest) {
                is SDKFakeReaderActionRequest.OnCardBehaviourRequired ->
                    readerActionRequest.provideCardBehaviour(
                        SDKFakeReaderActionRequest.OnCardBehaviourRequired.CardReadBehaviour.ApproveCardRead(
                            fakeCard = SDKFakeCard.Emv.Contact(
                                brand = SDKFakeCardBrand.Visa,
                                cardNumber = "4557881321510713",         
                                cvmResult = SDKCvmResult.PIN,
                                expireDate = "0429",
                                serviceCode = "",
                                availableEmvApps = listOf()
                            )
                        )
                    )
                else -> { /* Other actions */ }
            }
        }
    }
)

Decline

Simulates a card read that is declined. The decline can occur either before or after online authorization. The details of the card and the reason for the decline are provided using the appropriate classes within Decline.

Decline.BeforeGoingOnline

Represents a decline that occurs before attempting online authorization. The reason for the decline is specified using the Reason enum.

SDKFakeInstallerProvider.getInstaller(
    object : SDKFakeActionRequestCallback {
        override fun onActionRequired(readerActionRequest: SDKFakeReaderActionRequest) {
            when (readerActionRequest) {
                is SDKFakeReaderActionRequest.OnCardBehaviourRequired ->
                    readerActionRequest.provideCardBehaviour(
                        SDKFakeReaderActionRequest.OnCardBehaviourRequired.CardReadBehaviour.Decline.BeforeGoingOnline(
                            reason = SDKFakeReaderActionRequest.OnCardBehaviourRequired.CardReadBehaviour.Decline.BeforeGoingOnline.Reason.EmvCardBlocked
                        )
                    )
                else -> { /* Other actions */ }
            }
        }
    }
)

Possible Reasons for Reason Enum:

• OfflineDeclined: The transaction was declined offline. Resulting in a recoverable error SDKTransactionError.TransactionResult.Declined.Other(Reason.OfflineDeclined).
• DoFallback: The terminal requests fallback to another card reading method. Resulting in a recoverable error SDKTransactionError.TransactionResult.Declined.Other(Reason.DoFallback).
• NfcTryAgain: The cardholder is asked to retry NFC tap. Resulting in a recoverable error SDKTransactionError.TransactionResult.Declined.Other(Reason.NfcTryAgain).
• SeePhone: The cardholder is instructed to complete the transaction using their phone. Resulting in a recoverable error SDKTransactionError.TransactionResult.Declined.Other(Reason.SeePhone).
• EmvCardBlocked: The EMV card is blocked. Resulting in a recoverable error SDKTransactionError.TransactionResult.Declined.Other(Reason.EmvCardBlocked).
• Terminated: The transaction was terminated. Resulting in a recoverable error SDKTransactionError.TransactionResult.Terminated.

Decline.AfterGoingOnline

Represents a decline that occurs after online authorization. This scenario simulates a transaction where the card is approved online by the development environment simulator but is subsequently declined by the reader itself. This triggers a reversal process and results in a recoverable error SDKTransactionError.TransactionResult.Declined.Other(Reason.OfflineDeclined).

The decline is associated with an EMV contact or contactless card, and its details are provided using the SDKFakeCard.Emv object.

SDKFakeInstallerProvider.getInstaller(
    object : SDKFakeActionRequestCallback {
        override fun onActionRequired(readerActionRequest: SDKFakeReaderActionRequest) {
            when (readerActionRequest) {
                is SDKFakeReaderActionRequest.OnCardBehaviourRequired ->
                    readerActionRequest.provideCardBehaviour(
                        SDKFakeReaderActionRequest.OnCardBehaviourRequired.CardReadBehaviour.Decline.AfterGoingOnline(
                            fakeCard = SDKFakeCard.Emv.Contact(
                                brand = SDKFakeCardBrand.Visa,
                                cardNumber = "4557881321510713",
                                cvmResult = SDKCvmResult.PIN,
                                expireDate = "0429",
                                serviceCode = "",
                                availableEmvApps = listOf()
                            )
                        )
                    )
                else -> {/* Other actions */ }
            }
        }
    }
)